Crate onig

This crate provides a safe wrapper around the Oniguruma regular expression library.

Examples

use onig::Regex;

let regex = Regex::new("e(l+)").unwrap();
for (i, pos) in regex.captures("hello").unwrap().iter_pos().enumerate() {
    match pos {
         Some((beg, end)) =>
             println!("Group {} captured in position {}:{}", i, beg, end),
         None =>
             println!("Group {} is not captured", i)
    }
}

Match vs Search

There are two basic things you can do with a Regex pattern; test if the pattern matches the whole of a given string, and search for occurences of the pattern within a string. Oniguruma exposes these two concepts with the match and search APIs.

In addition two these two base Onigurma APIs this crate exposes a third find API, built on top of the search API.

let pattern = Regex::new("hello").unwrap();
assert_eq!(true, pattern.find("hello world").is_some());
assert_eq!(false, pattern.is_match("hello world"));

The Match API

Functions in the match API check if a pattern matches the entire string. The simplest of these is Regex::is_match. This retuns a true if the pattern matches the string. For more complex useage then Regex::match_with_options and Regex::match_with_encoding can be used. These allow the capture groups to be inspected, matching with different options, and matching sub-sections of a given text.

The Search API

Function in the search API search for a pattern anywhere within a string. The simplist of these is Regex::find. This returns the offset of the first occurence of the pattern within the string. For more complex useage Regex::search_with_options and Regex::search_with_encoding can be used. These allow capture groups to be inspected, searching with different options and searching within subsections of a given text.

The Find API

The find API is built on top of the search API. Functions in this API allow iteration across all matches of the pattern within a string, not just the first one. The functions deal with some of the complexities of this, such as zero-length matches.

The simplest step-up from the basic search API Regex::find is getting the captures relating to a match with the Regex::capturess method. To find capture information for all matches within a string Regex::find_iter and Regex::captures_iter can be used. The former exposes the start and end of the match as Regex::find does, the latter exposes the whole capture group information as Regex::captures does.

The std::pattern API

In addition to the main Oniguruma API it is possible to use the Regex object with the std::pattern API. To enable support compile with the std-pattern feature. If you're using Cargo you can do this by adding the following to your Cargo.toml:

[dependencies.onig]
version = "1.2"
features = ["std-pattern"]

Structs

CaptureTreeNode	Capture Tree Node
CaptureTreeNodeIter	Caputres iterator
Captures	Captures represents a group of captured strings for a single match.
EncodedBytes	Byte Buffer
Error	This struture represents an error from the underlying Oniguruma libray.
FindCaptures	An iterator that yields all non-overlapping capture groups matching a particular regular expression.
FindMatches	An iterator over all non-overlapping matches for a particular string.
MatchParam	Parameters for a Match or Search.
MetaCharType	Syntax meta character types
Regex	This struct is a wrapper around an Oniguruma regular expression pointer. This represents a compiled regex which can be used in search and match operations.
RegexOptions	Regex parsing and compilation options.
RegexSplits	Yields all substrings delimited by a regular expression match.
RegexSplitsN	Yields at most N substrings delimited by a regular expression match.
Region	Represents a set of capture groups found in a search or match.
SearchOptions	Regex evaluation options.
SubCaptures	An iterator over capture groups for a particular match of a regular expression.
SubCapturesPos	An iterator over capture group positions for a particular match of a regular expression.
Syntax	Onig Syntax Wrapper
SyntaxBehavior	Defines the behaviour of regex operators.
SyntaxOperator	Defines the different operators allowed within a regex syntax.
TraverseCallbackAt	The order in which traverse callbacks are invoked

Enums

MetaChar

Meta Character State

Traits

EncodedChars	Encoded String Buffer
Replacer	Replacer describes types that can be used to replace matches in a string.

Functions

copyright	Get Copyright
define_user_property	Create a User Defined Proeprty
version	Get Version